home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / sem_mode.z / sem_mode
Encoding:
Text File  |  2002-10-03  |  9.8 KB  |  198 lines
  1.  
  2.  
  3.  
  4. sssseeeemmmm____mmmmooooddddeeee((((3333CCCC))))                                                      sssseeeemmmm____mmmmooooddddeeee((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _ssss_eeee_mmmm______mmmm_oooo_dddd_eeee - set the operation mode of a POSIX unnamed semaphore
  10.  
  11. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_eeee_mmmm_aaaa_pppp_hhhh_oooo_rrrr_eeee_...._hhhh_>>>>
  13.      _iiii_nnnn_tttt _ssss_eeee_mmmm______mmmm_oooo_dddd_eeee _((((_ssss_eeee_mmmm______tttt _****_s_e_m_,,,, _iiii_nnnn_tttt _c_m_d_[[[[_,,,, _a_r_g_]]]]_))))_;;;;
  14.  
  15. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  16.      _ssss_eeee_mmmm______mmmm_oooo_dddd_eeee is used to change the operation mode of the specified POSIX
  17.      unnamed semaphore _s_e_m. Changing a semaphore's default operation mode
  18.      allows applications to enable two levels of debug tracing, and apply
  19.      retry spinning.
  20.  
  21.      Semaphore types other than POSIX unnamed semaphores are not supported by
  22.      this function.
  23.  
  24.      _ssss_eeee_mmmm______mmmm_oooo_dddd_eeee is an IRIX extension to the POSIX interfaces and is not part of
  25.      the IEEE 1003.1b Standard.
  26.  
  27.      The operation mode is selected by setting _c_m_d to one of the following:
  28.  
  29.      _SSSS_EEEE_MMMM______MMMM_OOOO_DDDD_EEEE______TTTT_RRRR_AAAA_CCCC_EEEE_IIII_NNNN_IIII_TTTT
  30.           Initialize statistical tracing for _s_e_m, passing a pointer to a
  31.           user-allocated trace structure of type _ssss_eeee_mmmm______tttt_rrrr_aaaa_cccc_eeee______tttt as _a_r_g.  When
  32.           debug or meter tracing is enabled, the collected data is stored in
  33.           the trace structure. Upon initialization, the contents of the
  34.           structure is cleared.
  35.  
  36.           The trace structure must reside in memory accessible to all
  37.           threads/processes accessing _s_e_m, to allow them to update the traced
  38.           data.  If the semaphore is being shared across process boundarys,
  39.           the trace structure must be located at the same virtual address for
  40.           all processes.
  41.  
  42.           The application may access the contents of the trace structure at
  43.           any time.
  44.  
  45.           Note: Tracing is not supported for _nnnn_oooo_nnnn_----_ssss_hhhh_aaaa_rrrr_eeee_dddd unnamed semaphores,
  46.           used by pthread applications.
  47.  
  48.      _SSSS_EEEE_MMMM______MMMM_OOOO_DDDD_EEEE______MMMM_EEEE_TTTT_EEEE_RRRR_OOOO_NNNN
  49.           Enable metered tracing for _s_e_m.  Once a trace structure for _s_e_m has
  50.           been initialized, metered tracing can be enabled.  Enabling this
  51.           level of tracing causes metered information to be accumulated and
  52.           stored in the following trace structure fields (as operations
  53.           occur):
  54.  
  55.                _ssss_eeee_mmmm______wwww_aaaa_iiii_tttt_ssss: number of sem_wait operations
  56.  
  57.                _ssss_eeee_mmmm______wwww_aaaa_iiii_tttt_hhhh_iiii_tttt_ssss: number of times a thread/process called _ssss_eeee_mmmm______wwww_aaaa_iiii_tttt
  58.                without having to block
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. sssseeeemmmm____mmmmooooddddeeee((((3333CCCC))))                                                      sssseeeemmmm____mmmmooooddddeeee((((3333CCCC))))
  70.  
  71.  
  72.  
  73.                _ssss_eeee_mmmm______pppp_oooo_ssss_tttt_ssss: number of sem_post operations
  74.  
  75.                _ssss_eeee_mmmm______pppp_oooo_ssss_tttt_hhhh_iiii_tttt_ssss: number of times a thread/process called _ssss_eeee_mmmm______pppp_oooo_ssss_tttt
  76.                without having to wakeup a waiting thread/process
  77.  
  78.                _ssss_eeee_mmmm______wwww_aaaa_iiii_tttt_eeee_rrrr_ssss: number of threads/processes currently waiting on
  79.                the semaphore
  80.  
  81.                _ssss_eeee_mmmm______mmmm_aaaa_xxxx_wwww_aaaa_iiii_tttt_eeee_rrrr_ssss: maximum number of threads/processes that can
  82.                block on a semaphore at any given time
  83.  
  84.      _SSSS_EEEE_MMMM______MMMM_OOOO_DDDD_EEEE______MMMM_EEEE_TTTT_EEEE_RRRR_OOOO_FFFF_FFFF
  85.           Disable metered tracing for _s_e_m, leaving the contents of the trace
  86.           structure intact for future analysis.
  87.  
  88.      _SSSS_EEEE_MMMM______MMMM_OOOO_DDDD_EEEE______MMMM_EEEE_TTTT_EEEE_RRRR_RRRR_EEEE_SSSS_EEEE_TTTT
  89.           Clear the metered contents of the trace structure of semaphore _s_e_m.
  90.  
  91.      _SSSS_EEEE_MMMM______MMMM_OOOO_DDDD_EEEE______DDDD_EEEE_BBBB_UUUU_GGGG_OOOO_NNNN
  92.           Enable debug tracing for _s_e_m.  Once a trace structure for _s_e_m has
  93.           been initialized, debug tracing can be enabled.  Enabling this level
  94.           of tracing causes ownership and access information to be tracked and
  95.           stored in the following trace structure fields:
  96.  
  97.                _ssss_eeee_mmmm______oooo_wwww_nnnn_eeee_rrrr______pppp_iiii_dddd: process ID of the semaphore's current owner
  98.  
  99.                _ssss_eeee_mmmm______oooo_wwww_nnnn_eeee_rrrr______tttt_iiii_dddd: pthread ID of the semaphore's current owner
  100.  
  101.                _ssss_eeee_mmmm______oooo_wwww_nnnn_eeee_rrrr______pppp_cccc: program counter of the semaphore owner
  102.  
  103.                _ssss_eeee_mmmm______llll_aaaa_ssss_tttt______pppp_iiii_dddd: process ID of the last process to perform a
  104.                semaphore operation on _s_e_m
  105.  
  106.                _ssss_eeee_mmmm______llll_aaaa_ssss_tttt______tttt_iiii_dddd: pthread ID of the last pthread to perform a
  107.                semaphore operation on _s_e_m
  108.  
  109.                _ssss_eeee_mmmm______llll_aaaa_ssss_tttt______pppp_cccc: program counter of the last thread/process to to
  110.                perform a semaphore operation on _s_e_m
  111.  
  112.      _SSSS_EEEE_MMMM______MMMM_OOOO_DDDD_EEEE______DDDD_EEEE_BBBB_UUUU_GGGG_OOOO_FFFF_FFFF
  113.           Disable debug tracing for _s_e_m, leaving the contents of the trace
  114.           structure intact for future analysis.
  115.  
  116.      _SSSS_EEEE_MMMM______MMMM_OOOO_DDDD_EEEE______DDDD_EEEE_BBBB_UUUU_GGGG_RRRR_EEEE_SSSS_EEEE_TTTT
  117.           Clear the debug ownership contents of the trace structure of
  118.           semaphore _s_e_m.
  119.  
  120.      _SSSS_EEEE_MMMM______MMMM_OOOO_DDDD_EEEE______SSSS_PPPP_IIII_NNNN_SSSS_EEEE_TTTT
  121.           Apply a retry count _a_r_g to hold-off blocking in _ssss_eeee_mmmm______wwww_aaaa_iiii_tttt(3C) when
  122.           the semaphore _s_e_m is not immediately available.  The default POSIX
  123.           semaphore _ssss_eeee_mmmm______wwww_aaaa_iiii_tttt algorithm attempts to acquire a semaphore once,
  124.           and blocks the caller if the semaphore isn't available.  Applying a
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. sssseeeemmmm____mmmmooooddddeeee((((3333CCCC))))                                                      sssseeeemmmm____mmmmooooddddeeee((((3333CCCC))))
  136.  
  137.  
  138.  
  139.           retry count causes _ssss_eeee_mmmm______wwww_aaaa_iiii_tttt to retry semaphore acquisition _a_r_g times
  140.           (spinning) before blocking.  Retry counts remain in effect until the
  141.           application again sets the retry count to 0.
  142.  
  143.           Note: This operation mode is ignored on uni-processor systems.
  144.  
  145.      _ssss_eeee_mmmm______mmmm_oooo_dddd_eeee will fail if the following is true:
  146.  
  147.      [EINVAL]    Invalid parameter.
  148.  
  149. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  150.      _ssss_eeee_mmmm______iiii_nnnn_iiii_tttt(3C), _ssss_eeee_mmmm______pppp_oooo_ssss_tttt(3C), _ssss_eeee_mmmm______wwww_aaaa_iiii_tttt(3C), _ssss_eeee_mmmm______pppp_rrrr_iiii_nnnn_tttt(3C)
  151.  
  152. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  153.      Upon successful completion, a value of 0 is returned to the calling
  154.      process. Otherwise, a value of -1 is returned and _eeee_rrrr_rrrr_nnnn_oooo is set to
  155.      indicate the error.
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                                                         PPPPaaaaggggeeee 3333
  195.  
  196.  
  197.  
  198.